.\" Programming assignment of:
.\"   CS631 Advanced Programming in the UNIX Environment
.\"   https://www.cs.stevens.edu/~jschauma/631/
.\"
.Dd December 17, 2019
.Dt SISH 1
.Os
.Sh NAME
.Nm sish
.Nd a simple hell
.Sh SYNOPSIS
.Nm
.Op Fl x
.Op Fl c Ar command
.Sh DESCRIPTION
.Nm
implements a very simple command-line interpreter or shell.
It is suitable to be used interactively or as a login shell.
It only implements a very small subset of what would usually be expected
of a Unix shell, and does explicitly not lend itself as a scripting
language.
.Pp
.Sh OPTIONS
The following options are supported by
.Nm :
.Bl -tag -width _c_command
.It Fl c Ar command
Execute the given command.
.It Fl x
Enable tracing:
Write each command to standard error, preceeded by '+'.
.El
.Sh DETAILS
.Nm
allows for the execution of the given commands with a minimal amount of
niceties.
.Pp
When
.Nm
is invoked and no commands are passed via the
.Fl c
flag, it will print a simple prompt to stdout.
It then reads commands from the controlling terminal, executing them as
one would expect.
.Ss Lexical Structure
The shell reads input in terms of lines and breaks it up into words at
whitespace (blanks and tabs), and at certain sequences of characters that
are special to the shell called ``operators''.
There are two types of operators: control operators and redirection
operators:
.Bl -ohang -offset indent
.It "Control operators:"
.Dl \*[Am] | \*[Lt]newline\*[Gt]
.It "Redirection operators:"
.Dl \*[Lt] \*[Gt] \*[Gt]\*[Gt]
.El
.Ss Redirection
.Nm
supports the following three input-/output- redirection operators:
.Bl -tag -width ___file -offset indent
.It \*[Gt] file
Redirect standard output to file.
Mutually exclusive with the \*[Gt]\*[Gt] opreator.
.It \*[Gt]\*[Gt] file
Append standard output to file.
Mutually exclusive with the \*[Gt] opreator.
.It \*[Lt] file
Redirect standard input from file.
.El
.Ss Pipeines
A pipeline is a sequence of one or more commands separated by the control
operator '|'.
The standard output of all but the last command is connected to the
standard input of the next command.
The standard output of the last command is, absent any redirection
operators, the controlling terminal.
.Ss Background Commands -- \*[Am]
If a command is terminated by the control operator ampersand (\*[Am]), the
shell executes the command asynchronously -- that is, the shell does not
wait for the command to finish before prompting the user for the next
command.
.Ss Builtins
.Nm
supports the following builtins (which are taking precedence over any
non-builtin commands):
.Bl -tag -width echo__word_
.It cd Op Ar dir
Change the current working directory.
If
.Ar dir
is not specified, change to the user's home directory.
.It echo Op Ar word
Print the given word, followed by a '\\n'.
The following special values are supported:
.Bl -tag -width __
.It $?
The exit status of the last command.
.It $$
The current process ID.
.El
.It exit
Exit the current shell.
.El
.Ss Command Execution
If a sequence of words does not begin with a builtin,
.Nm
will attempt to execute it as a command, possibly utilizing the current
PATH.
.Ss Environment
.Nm
sets the following environment variables:
.Bl -tag -width shell_
.It SHELL
the path of the executable of
.Nm
.El
.Sh EXAMPLES
The following sequence of commands shows common usage of
.Nm :
.Bd -literal 
$ sish
sish$ echo $$
6465
sish$ ls
file1   file2
sish$ ls | wc -l
    2
sish$ echo $?
0
sish$ echo Writing a shell is fun! > /tmp/out
sish$ < /tmp/out cat
Writing a shell is fun!
sish$ find / >/dev/null &
sish$ 
sish$ aed -e <file >file.enc
sish$ cmd | sort | uniq -c | sort -n
 121 foo
 304 bar
sish$ something
something: command not found
sish$ echo $?
127
sish$ rm /etc/passwd
rm: /etc/passwd: Permission denied
sish$ echo $?
1
sish$ exit
$ sish -c date
Sat Nov 29 21:18:07 EST 2014
$ sish -c "date +%s"
1576614990
$ sish -x
sish$ ls
+ ls
file1    file2
sish$ ls | wc -l
+ ls
+ wc -l
    2
sish$ cd /tmp
+ cd /tmp
sish$ pwd
+ pwd
/tmp
sish$ cd
+ cd
sish$ pwd
+ pwd
/home/jschauma
sish$ exit
+ exit
$ 
.Ed
.Sh EXIT STATUS
.Nm
returns the exit status of the last command it executed or a status of 127
if the given command could not be executed for any reason.
.Sh SEE ALSO
.Xr bash 1 ,
.Xr ksh 1 ,
.Xr sh 1 ,
.Xr execve 2 ,
.Xr fork 2
.Sh HISTORY
Writing a simple shell has been a frequent assignment in many Unix
programming classes.
This particular version was first assigned in the class
.Ar Advanced Programming in the UNIX Environment
at Stevens Institute of Technology by
.An Jan Schaumann
.Aq jschauma@stevens.edu
in the Fall of 2014.
